---
title: Switch
description: Using the switch machine in your project.
package: "@zag-js/switch"
---

A switch allows users to turn an individual option on or off.

<Resources pkg="@zag-js/switch" />

<Showcase id="Switch" />

**Features**

- Sync with `disabled` state of fieldset
- Sync with form `reset` events
- Can be toggled programmatically

## Installation

To use the switch machine in your project, run the following command in your
command line:

<CodeSnippet id="switch/installation.mdx" />

## Anatomy

To set up the switch correctly, you'll need to understand its anatomy and how we
name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.

<Anatomy id="switch" />

## Usage

First, import the switch package into your project

```jsx
import * as zagSwitch from "@zag-js/switch"
```

The switch package exports two key functions:

- `machine` — The state machine logic for the switch widget.
- `connect` — The function that translates the machine's state to JSX attributes
  and event handlers.

Next, import the required hooks and functions for your framework and use the
switch machine in your project 🔥

<CodeSnippet id="switch/usage.mdx" />

### Disabling the switch

To make a switch disabled, set the `disabled` property to `true`.

```jsx {3}
const service = useMachine(zagSwitch.machine, {
  disabled: true,
})
```

### Making it checked by default

Use the `defaultChecked` property to make a switch checked by default.

```jsx {3}
const service = useMachine(zagSwitch.machine, {
  defaultChecked: true,
})
```

### Listening for changes

When the switch value changes, the `onCheckedChange` callback is invoked.

```jsx {3-5}
const service = useMachine(zagSwitch.machine, {
  onCheckedChange(details) {
    // details => { checked: boolean }
    console.log("switch is:", details.checked ? "On" : "Off")
  },
})
```

### Usage within forms

To use switch within forms, use the exposed `inputProps` from the `connect`
function and ensure you pass `name` value to the machine's context. It will
render a hidden input and ensure the value changes get propagated to the form
correctly.

```jsx {3}
const service = useMachine(zagSwitch.machine, {
  name: "feature",
})
```

## Styling guide

Earlier, we mentioned that each switch part has a `data-part` attribute added to
them to select and style them in the DOM.

### Focused State

When the switch input is focused, the `data-focus` attribute is added to the
root, control and label parts.

```css
[data-part="root"][data-focus] {
  /* styles for root focus state */
}

[data-part="control"][data-focus] {
  /* styles for control focus state */
}

[data-part="label"][data-focus] {
  /* styles for label focus state */
}
```

### Disabled State

When the switch is disabled, the `data-disabled` attribute is added to the root,
control and label parts.

```css
[data-part="root"][data-disabled] {
  /* styles for root disabled state */
}

[data-part="control"][data-disabled] {
  /* styles for control disabled state */
}

[data-part="label"][data-disabled] {
  /* styles for label disabled state */
}
```

### Invalid State

When the switch is invalid, the `data-invalid` attribute is added to the root,
control and label parts.

```css
[data-part="root"][data-invalid] {
  /* styles for root invalid state */
}

[data-part="control"][data-invalid] {
  /* styles for control invalid state */
}

[data-part="label"][data-invalid] {
  /* styles for label invalid state */
}
```

## Methods and Properties

### Machine Context

The switch machine exposes the following context properties:

<ContextTable name="switch" />

### Machine API

The switch `api` exposes the following methods:

<ApiTable name="switch" />

### Data Attributes

<DataAttrTable name="switch" />

## Accessibility

Adheres to the
[Switch WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/)

### Keyboard Interactions

<KeyboardTable name="switch" />
